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Purpose 


This document presents an overview of Application Programming Interfaces (API). 
The following topics are discussed: 


e Definitions 

e APIs Supported in Attachmate Products 
e How HLLAPI Works 

e Types of HLLAPI 

e DLLs for Each Type of HLLAPI 

e API-related Issues 

© Tool Kits 


Definitions 


API - Application Programming Interface 

An API is an interface into an application which allows a programmer to write a 
program to interact with that application. The most common API in Attachmate 
products is HLLAPI in its many types. 


HLLAPI -High Level Language API 

HLLAPI allows a programmer to use any high level language (e.g., Visual Basic, C, 
C++, COBOL, Pascal) to write a program for interacting with the host presentation 
space. HLLAPI comes in different types (e.g., EHLLAPI, WinHLLAPI, and 
Attachmate HLLAPI). Each comes in 16- and 32-bit versions. 


ATMAPI -Enterprise Access Library (EAL) 

ATMAPTIT is a standard API across most Attachmate emulators (e.g., EXTRA! 
Personal Client, EXTRA! for Windows, IRMA for the Mainframe for Windows, KEA!). 
ATMAPI is available in 16- and 32-bit version, but not for every emulator. 


DDE -Dynamic Data Exchange 

DDE is a Windows 3.x technology, replaced by OLE. It allows applications to interact 
with other DDE-enabled applications for exchanging data. For example, DDE can be 
used through Excel to grab host data from EXTRA! and display it in a spreadsheet. 


OLE -Object Linking and Embedding 

OLE is a 32-bit technology backed by Microsoft. The next generation is Activex 
which extends OLE to the Web. OLE is used to embed an object, such as an Excel 
spreadsheet, into another application (e.g., a Word document). 


OLE Automation 

OLE Automation is the process of manipulating an application's exposed objects 
through a macro or programming language. This technology is used extensively in 
EXTRA! Personal Client, where much of the emulator is exposed as objects. The 
emulator and host applications can be manipulated using this interface. The 
EXTRA! Objects technology takes this to the extreme, where the entire emulator is 
exposed as objects, and a programmer can design it however they want. EXTRA! 
Basic uses OLE Automation in EXTRA! Personal Client 6.x. 


DLL-Dynamic Link Library 

A DLL is an executable program module that is linked to an application and 
performs a function (e.g., HLLAPI calls). A DLL does not reside in memory until 
requested by an application, and is removed from memory when all programs using 
it have exited. 


APIs Supported in Attachmate Products 
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*NOTE: All EXTRA! Personal Client derivatives are included (e.g., RALLY! 32-bit). 


How HLLAPI Works 


HLLAPI is a set of functions that are used to write applications that communicate 
with a host computer. Through HLLAPI functions, an application can interact with 
the host in much the same way an operator would interact using a 3279 or 5250 
terminal. When a program calls a function, the HLLAPI software interprets the data 
and passes it to the 3279 or 5259 presentation-space buffer for processing. 


With HLLAPI, applications can easily be written to accomplish the following tasks: 


e Automate logon procedures. 

e Develop custom menus as a front end for any host application. 
e Simplify user screens for complex host applications. 

e Process data or transfer files during off-hours, unattended. 

e Combine data from multiple hosts applications. 


When a program calls a HLLAPI function, the following actions occur: 


1. Windows finds the function in the HLLAPI DLL and passes the required 
parameters to the function. 


2. The DLL interprets the request. 
3. The DLL sends the request to the host access software. 


4. The host access software processes the request, performs any necessary host 
communications, and returns the result of the request to the DLL. 


5. The DLL sends the results back to the application through the returning 
parameters. 


Types of HLLAPI 


EHLLAPI 

EHLLAPI is an industry standard API originally developed by IBM. It's the oldest 
and most common type of HLLAPI, and is widely supported across Windows 
emulators. If a developer wishes to write an application that works with terminal 
emulation software from any vendor, they should write the application using the 
EHLLAPI interface. 


WinHLLAPI 

WinHLLAPI is the Microsoft standard Windows HLLAPI. It is based on IBM's 
EHLLAPI, but is extended to include additional features for Windows programmers. 
These extensions include additional functions that support asynchronous 
operations designed for the event-driven, message-based nature of the Windows 


environment. WinHLLAPI is part of Microsoft's Windows Open Systems Architecture 
(WOSA), and is supported by most Windows terminal emulation vendors. 


Attachmate HLLAPI 

Attachmate's proprietary HLLAPI is often referred to as a multi-tasking API, 
because it allows a single HLLAPI client application to interact with multiple host 
sessions at the same time (with EHLLAPI and WinHLLAPI, a program must 
disconnect from one session before it can connect and interact with another). The 
interface is tailored to those writing programs in C and C++. 


DOS HLLAPI 
The DOS HLLAPI Pass-through allows users to run DOS HLLAPI applications with 
Windows emulators. The HLLAPI supported is essentially the same as EHLLAPI. 


Enterprise Access Library (EAL, ATMAPI) 

ATMAPI is an Attachmate proprietary API based on Attachmate HLLAPI, and was 
originally created for programmers using non-C and C++ languages (e.g., Visual 
Basic and PowerBuilder). An advantage of ATMAPT is that it can be used not only 
with EXTRA! for Windows and EXTRA! Personal Client, but also with the IRMA for 
the Mainframe for Windows, RALLY!, KEA!, and INFOConnect emulators.Each type of 
HLLAPI discussed above is available in 16- and 32-bit versions. There is not much 
difference between the 16- and 32-bit versions other than the DLL name. The 
function declarations are slightly different (some parameters are changed from 
integers to longs), but the functions themselves are called in the same way. 


NOTE: JBM recently released new specifications for 32-bit EHLLAPI which are 
different from the 32-bit EHLLAPI developed by Attachmate, and they are not 
compatible. To work around this, EXTRA! Personal Client 6.39 provides separate 
DLLs for the two versions of 32-bit EHLLAPI. 


DLLs for Each Type of HLLAPI 
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*NOTE: All EXTRA! Personal Client derivatives are included (e.g., RALLY! 32-bit). 


EXTRA! Personal Client and its derivatives contain 16- and 32-bit versions of the 
HLLAPI DLLs. The 16-bit DLLs are merely "thunking" DLLs that call into the 32-bit 
ones. For example, if a call is made into ACS3EHAP.DLL, it makes a call into 
EHLAPI32.DLL, which processes the HLLAPI call as usual. Therefore, 16-bit HLLAPI 
applications will run with EXTRA! Personal Client, but 32-bit HLLAPI applications 
will not run with 16-bit emulators (e.g., EXTRA! for Windows and IRMA for the 
Mainframe for Windows). 


Even though most of the Attachmate emulators use HLLAPI DLLs of the same name 
(all use ACS3EHAP.DLL for EHLLAPI, except KEA!), it's important for an application 
to use the correct DLL for the emulator. Each DLL is written specifically for the 
emulator it ships with. 


API-related Issues 


Timing Issues 

Timing issues are the most common issues encountered by HLLAPI developers. 
Typical problems involve knowing when the X () clock has cleared. The X () clock in 
Attachmate emulators sometimes flickers so it's difficult for a program to know 
when the X () clock has actually cleared. In addition, faster PCs, slower hosts, or 
different connection types can affect the timing of an API application. The problem 
usually manifests itself if the program sends data to the host when the host isn't 
ready, or the program thinks it should be on a certain host screen when it's not 
there yet. 


Configuration Issues 

When an API application doesn't work, often the emulator or the application isn't 
configured properly. The most common configuration problems include incorrect 
pathing, no session short name, incorrect DOS HLLAPI Pass-through configuration, 
or the API application is using the wrong DLL. 


Changes With Different Versions 


Sometimes an application will work with one version of a product, but fails with a 
later version. Occasionally, an attempt to fix one problem in the APIs breaks 
something else. In addition, developers get used to functions behaving in certain 
ways, and if those functions change (even when the changes are to fix a problem), 
programs must be changed too. 


Intermittent Errors 

This is the most difficult type of problem that can occur. Problems that are not 
reproducible on demand are hard to track down. These problems may be timing 
issues, memory issues, bugs in the code (developer's or Attachmate's), or 
communications issues disguised as API issues. 


Tool Kits 


Attachmate sells several different API tool kits. API tool kits are intended for 
programmers writing applications with HLLAPI or the other APIs, and are not 
designed for end users. It is expected that programmers using tool kits have a 
working knowledge of Microsoft Windows, 3279 or 5259 concepts, and the 
programming language and compiler they are using. 


EXTRA! Developer API SDK 


Main Components 
The main components of the EXTRA! Developer API SDK are shown below. 


Documentation 

The tool kit provides documentation for EHLLAPI and Attachmate HLLAPI. 
WinHLLAPI is documented by Microsoft, however the WinHLLAPI documentation 
set (on-line and a help file) is included in the EXTRA! Developer API SDK. A general 
Programmer's Guide, which introduces the basics of HLLAPI programming, is also 
included. OLE Automation documentation is provided with EXTRA! Personal Client, 
so it is not included in the SDK. 


Samples 

16- and 32-bit samples are provided for Attachmate HLLAPI, EHLLAPI, WinHLLAPI, 
the Enterprise Access Library, and OLE Automation for the following development 
environments: 


Cc 

Delphi 
PowerBuilder 
Visual Basic 
Visual C++ 


Samples are not provided for all API interfaces with all development environments. 
For example, only Visual Basic and C samples are provided for EHLLAPI and 
WinHLLAPI. 


Include Files 

Header and include files are provided for each API interface and for each 
development environment. For example, the ATMAPI.BAS header file is included for 
Visual Basic, and the ASC3EHAP.H header file is included for C. 


QuickApp 


Main Components 
The main components of QuickApp are shown below. They are available in 16- and 
32-bit versions. 


Enterprise Access Library (ATMAPI) 

ATMAPI includes documentation, samples, and header files. It also includes the 
Enterprise Access Tutor, which allows a programmer to execute each function, as 
well as copy and paste the appropriate code into their application. 


Navigation Components 

Navigation components include the Recorder and several custom controls (OCXs) 
used to record host screens, and the keystrokes necessary to move between them. 
Once host screens and keystrokes are recorded, it is easy to build an application 
that uses the recorded information to move through the host screens and retrieve 
data. Advantages to using the navigation components include the following: 


e The programmer has much less code to write than with traditional HLLAPI 
applications. 

e QuickApp takes care of most timing and host synchronization problems that 
occur with HLLAPI. 


QuickAPI 

QuickAPI is an Attachmate proprietary API. It uses WinHLLAPI and works with 
most host access products that support WinHLLAPI, including EXTRA! Personal 
Client, EXTRA! for Windows, IRMA for the Mainframe for Windows, and KEA!. 


Additional Custom Controls 

QuickApp contains additional custom controls carried over from the TOOLS! for 
Visual Basic and PowerBuilder products. One of these is the Terminal control, which 
displays a host screen within an application window. 


Development Tools Supported 
The following development tools are supported with QuickApp: 


Delphi 
PowerBuilder 
Visual Basic 
Visual C++ 
CA-Visual Realia 


Supported Host Access Products 
The following host access (emulation) products are supported with QuickApp: 


e EXTRA! Personal Client 6.2 or later 

e EXTRA! for Windows 4.3 or later 

e IRMA for the Mainframe for Windows 3.9 or later 
e NetWare 3279 LAN Professional 2.9 or later 

@ RALLY! 1.13 or later 

e KEA! 4.23 or later 

e INFOConnect 


QuickApp replaces TOOLS! for Visual Basic and TOOLS! for PowerBuilder. 
EXTRA! Host Publishing System 


The EXTRA! Host Publishing System converts host data into HyperText Markup 
Language (HTML) so that host data can be accessed from a Web browser. At this 
time, only Visual Basic is supported. A server version of QuickApp is included. 


EXTRA! Objects SDK 


EXTRA! Objects SDK is a tool kit used to develop applications using EXTRA! 
Objects. EXTRA! Objects are OLE 2.8 compatible software building blocks used to 
build a complete emulator application. 
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